home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_3.5 / Documentation / Autodocs / speedbar_gc.doc < prev    next >
Encoding:
Text File  |  1999-10-29  |  12.8 KB  |  381 lines
  1. TABLE OF CONTENTS
  2.  
  3. speedbar_gc/--datasheet--
  4. speedbar_gc/SPEEDBAR_GetClass
  5. speedbar_gc/AllocSpeedButtonNodeA
  6. speedbar_gc/FreeSpeedButtonNode
  7. speedbar_gc/GetSpeedButtonNodeAttrsA
  8. speedbar_gc/SetSpeedButtonNodeAttrsA
  9. speedbar_gc/--datasheet--                           speedbar_gc/--datasheet--
  10.  
  11.     NAME
  12.         speedbar_gc -- create speedbar BOOPSI objects
  13.  
  14.     SUPERCLASS
  15.         gadgetclass
  16.  
  17.     REQUIRES
  18.         bevel.image
  19.  
  20.     DESCRIPTION
  21.         This classes provides a simple way to create and manage
  22.         "Speed Bars", also commonly called Button Bars, Tool Docs, etc.
  23.  
  24.         A speed bar is a horizontal row or vertical column of button
  25.         gadgets, usually with an image face denoting some program function.
  26.         The speedbar gadget could be placed in the main programs window
  27.         or perhaps its own window to form a floating speedbar/tooldoc.
  28.  
  29.         An advantages that this class provides:
  30.  
  31.          > Speedbar button strip created & removed as a single gadget.
  32.  
  33.          > Help strings for each button can be provided, and displayed
  34.            in a window title bar while a button is depressed.
  35.  
  36.          > Supports Right Mouse Button abort.
  37.  
  38.          > Supports window relativity.
  39.  
  40.          > Custom centered images.
  41.  
  42.          > Ability to change background color of the speed bar strip
  43.            or use fill hook pattern.
  44.  
  45.          > Horizontal or Vertical speed bar orientation.
  46.  
  47.          > Supports hiding and exposing speed buttons in the bar.
  48.  
  49.          > Supports scrolling additional speed buttons in to view
  50.            via holding down the SHIFT key while clicking and
  51.            dragging the mouse left/right or up/down depending on
  52.            the SPEEDBAR_Orientation setting.
  53.  
  54.          > Supports OM_NOTIFY and may be attached to either
  55.            button.gadget, scroller.gadget and/or propgclass to scroll
  56.            the speed buttons if more buttons exist that are visible
  57.            within its bounds. However, this as a slight unresolvable bug.
  58.  
  59.     METHODS
  60.         OM_NEW -- Passed to superclass, defaults set, then OM_SET.
  61.  
  62.         OM_SET -- Passed to superclass, options tags set then rendered.
  63.  
  64.         OM_GET -- Custom tag returned or passed to superclass.
  65.  
  66.         OM_UPDATE -- Passed to superclass, options set then rendered.
  67.  
  68.         OM_NOTIFY -- Passed to superclass, options set then rendered.
  69.  
  70.         OM_DISPOSE -- Passed to superclass.
  71.  
  72.         GM_RENDER -- Passed to superclass, then speedbar is rendered.
  73.  
  74.         GM_HITTEST -- Overrides supperclass, returns GMR_HITTEST.
  75.  
  76.         GM_GOACTIVE -- Passed to superclass, speedbar activated.
  77.  
  78.         GM_HANDLEINPUT -- Overrides supperclass, all input processed.
  79.  
  80.         GM_GOINACTIVE -- Passed to superclass, speedbar deactivated.
  81.  
  82.         GM_DOMAIN -- Returns GDOMAIN_MINIMUM and GDOMAIN_MAXIMUM dimensions.
  83.  
  84.     ATTRIBUTES
  85.         SPEEDBAR_Buttons (struct List *)
  86.             An Exec list.  Nodes in this list must be allocated with
  87.             AllocSpeedButtonNodeA().
  88.  
  89.             See the included SpeedBarTest.c example for additional information.
  90.             Passing a NULL list will remove all buttons from the speedbar and
  91.             detatch the buttons.  Passing ~0 will detach all buttons but not
  92.             erase the display, useful when working on the list data, or while
  93.             changing button lists.
  94.  
  95.             Applicability is (OM_NEW,OM_SET,OM_GET)
  96.  
  97.         SPEEDBAR_Orientation (WORD)
  98.             Define orientation of the speedbar's button strip.
  99.  
  100.             Accepted values as defined in <gadgets/speedbar.h> are: 
  101.  
  102.                SBORIENT_HORIZ
  103.                SBORIENT_VERT
  104.  
  105.             Defaults to SBORIENT_HORIZ
  106.  
  107.  
  108.             Applicability is (OM_NEW,OM_SET,OM_GET)
  109.  
  110.         SPEEDBAR_Background (WORD)
  111.             Background colour to appear behind gadget.
  112.  
  113.             Defaults to 0.
  114.  
  115.             Applicability is (OM_NEW,OM_SET,OM_GET)
  116.  
  117.         SPEEDBAR_Window (struct Window *)
  118.             This Window's TitleBar will changed to the selected button's
  119.             help text while the button remains selected.
  120.  
  121.             Defaults to NULL.
  122.  
  123.             Applicability is (OM_NEW,OM_SET,OM_GET)
  124.  
  125.             NOTE: SPEEDBAR_Screen is *NOT* implemented.
  126.  
  127.         SPEEDBAR_StrumBar (BOOL)
  128.             Enable "strumming" mode, where by you can drag the mouse
  129.             over the button bar to view the help titles and release
  130.             mouse button select the speed button under the mouse.
  131.          
  132.             Defaults to FALSE.
  133.  
  134.             Applicability is (OM_NEW,OM_SET)
  135.  
  136.             NOTE: SPEEDBAR_StrumBar has been disabled to support other
  137.                   features available now, and in the future.
  138.  
  139.         SPEEDBAR_OffButton (SHORT)
  140.             Disconnect a specified button ID from the speedbar display,
  141.             but does not remove or deallocate button from the list.
  142.  
  143.             Applicability is (OM_SET, OM_UPDATE)
  144.  
  145.         SPEEDBAR_OnButton (SHORT)
  146.             Reconnect specified button ID to the speedbar.
  147.  
  148.             Applicability is (OM_SET, OM_UPDATE)
  149.  
  150.         SPEEDBAR_ScrollLeft (BOOL)
  151.             Scrolls the speedbuttons to the Left or Up depending on
  152.             gadget orientation.
  153.  
  154.             Applicability is (OM_SET, OM_UPDATE)
  155.  
  156.         SPEEDBAR_ScrollRight (BOOL)
  157.             Scrolls the speedbuttons to the Right or Down depending on
  158.             gadget orientation.
  159.  
  160.             Applicability is (OM_SET, OM_UPDATE)
  161.  
  162.         SPEEDBAR_Top (WORD)
  163.             Set or retrieve the SpeedButton ID of the Top (read First
  164.             Visible) gadget in the button list.
  165.  
  166.             Applicability is (OM_SET, OM_UPDATE, OM_GET, OM_NOTIFY)
  167.  
  168.         SPEEDBAR_Visible (WORD)
  169.             Retrieve the number of speed buttons visible within
  170.             the gadget's container bounds.
  171.  
  172.             Applicability is (OM_GET, OM_NOTIFY)
  173.  
  174.         SPEEDBAR_Total (WORD)
  175.             Retrieve the total number of speed buttons in the button list.
  176.             SPEEDBAR_Total, SPEEDBAR_Visible and SPEEDBAR_Top could be
  177.             mapped to a scroller's matching PGA tags to scroll the button
  178.             list if so desired.
  179.  
  180.             Applicability is (OM_GET, OM_NOTIFY)
  181.  
  182.         SPEEDBAR_BevelStyle (WORD)
  183.             Set bevel box style around the speed bar. In some cases
  184.             complex speedbars might be built via a series of speedbars
  185.             in a layout object group and it would be desirable to
  186.             select other bevel styles such as BVS_NONE, which under any
  187.             bevel style preferences in use, it will not render a bevel.
  188.  
  189.             Defaults to BVS_BUTTON.
  190.  
  191.             Applicability is (ON_NEW, OM_SET, OM_GET)
  192. speedbar_gc/SPEEDBAR_GetClass                   speedbar_gc/SPEEDBAR_GetClass
  193.  
  194.     NAME
  195.         SPEEDBAR_GetClass -- Gets the pointer to the speedbar class. (V40)
  196.  
  197.     SYNOPSIS
  198.         speedbar_class = SPEEDBAR_GetClass();
  199.         D0
  200.  
  201.         Class * SPEEDBAR_GetClass(VOID);
  202.  
  203.     FUNCTION
  204.         Obtains the pointer to the SpeedBar gadget class for use with
  205.         NewObject().  This function always returns a valid pointer so
  206.         you do not need to check it.  The reason is that if the library
  207.         opens fine, then the pointer returned is already setup.  (Of course
  208.         this implies that if opening the library fails, you shouldn't be
  209.         calling this.)
  210.  
  211.         Note that this function does not create the class, that is done
  212.         when the class library is opened.
  213.  
  214.     INPUTS
  215.         Nothing.
  216.  
  217.     RESULT
  218.         speedbar_class - Pointer to the SpeedBar gadget class.
  219.  
  220.     SEE ALSO
  221. speedbar_gc/AllocSpeedButtonNodeA          speedbar_gc/AllocSpeedButtonNodeA
  222.  
  223.     NAME
  224.         AllocSpeedButtonNodeA -- Allocate a SpeedBar node. (V40)
  225.  
  226.     SYNOPSIS
  227.         struct Node * AllocSpeedButtonNode(UWORD, Tag, ...)
  228.         node = AllocSpeedButtonNode(number, Tag, ...)
  229.  
  230.         struct Node * AllocSpeedButtonNodeA(UWORD, struct TagItem *)
  231.         node = AllocSpeedButtonNodeA(number, taglist)
  232.  
  233.     FUNCTION
  234.         Allocates a node that can be added to the Exec linked list of
  235.         labels in the speedbar.  This is the only way to allocate a
  236.         node for this list, you cannot allocate nodes yourself because
  237.         the SpeedBar class uses a private node structure.
  238.  
  239.     INPUTS
  240.         number - Places value in node->sbn_Node.ln_Pri, and is the
  241.             numeric ID of the button within the bar. Note the current
  242.             limitation, ln_Pri is a BYTE. This will be addressed, and
  243.             *posibly* made obsolete and overridden by SBNA_ButtonID.
  244.  
  245.         taglist - Attributes for the node, passed onto
  246.             SetSpeedButtonNodeAttrsA().
  247.  
  248.     RESULT
  249.         node - A node that can be added into the Exec list of labels for
  250.             a SpeedBar gadget.
  251.  
  252.     SEE ALSO
  253.         FreeSpeedButtonNode(), SetSpeedButtonNodeAttrsA()
  254. speedbar_gc/FreeSpeedButtonNode             speedbar_gc/FreeSpeedButtonNode
  255.  
  256.     NAME
  257.         FreeSpeedButtonNode -- Free a SpeedBar node. (V40)
  258.  
  259.     SYNOPSIS
  260.         VOID FreeSpeedButtonNode(struct Node *)
  261.         FreeSpeedButtonNode(node)
  262.  
  263.     FUNCTION
  264.         Frees a SpeedButtonNode allocated with AllocSpeedButtonNodeA().
  265.  
  266.     INPUTS
  267.         node - The node to free.
  268.  
  269.     SEE ALSO
  270.         AllocSpeedButtonNodeA()
  271. speedbar_gc/GetSpeedButtonNodeAttrsA    speedbar_gc/GetSpeedButtonNodeAttrsA
  272.  
  273.     NAME
  274.         GetSpeedButtonNodeAttrsA -- Get attributes about a SpeedBar node. (V40)
  275.  
  276.     SYNOPSIS
  277.         VOID GetSpeedButtonNodeAttrs(struct Node *, Tag, ...)
  278.         GetSpeedButtonNodeAttrs(node, firsttag, ...)
  279.  
  280.         VOID GetSpeedButtonNodeAttrsA(struct Node *, struct TagItem *)
  281.         GetSpeedButtonNodeAttrsA(node, taglist)
  282.  
  283.     FUNCTION
  284.         The SpeedBar uses a private node structure and all attributes
  285.         are hidden, and must therefore be accessed with this function.
  286.  
  287.     INPUTS
  288.         node - The SpeedBar node to get the information on.
  289.         taglist - A tag list of attributes to get.  ti_Tag is the attribute
  290.             to get and ti_Data is a pointer to a location to copy the result
  291.             to.
  292.  
  293.     SEE ALSO
  294.         SetSpeedButtonNodeAttrsA()
  295. speedbar_gc/SetSpeedButtonNodeAttrsA     speedbar_gc/SetSpeedButtonNodeAttrsA
  296.  
  297.     NAME
  298.         SetSpeedButtonNodeAttrsA -- Set attributes of a SpeedBar node. (V40)
  299.  
  300.     SYNOPSIS
  301.         VOID SetSpeedButtonNodeAttrs(struct Node *, Tag, ...)
  302.         SetSpeedButtonNodeAttrs(node, firsttag, ...)
  303.  
  304.         VOID SetSpeedButtonNodeAttrsA(struct Node *, struct TagItem *)
  305.         SetSpeedButtonNodeAttrsA(node, taglist)
  306.  
  307.     FUNCTION
  308.         Changes attributes for a SpeedBar node.  Since the SpeedBar
  309.         class uses a private node structure, this is the only way to change
  310.         node attributes.
  311.  
  312.         You may NOT change node attributes when the node is in a list
  313.         attached to a SpeedBar gadget.  You must first detach the list
  314.         with SPEEDBAR_Labels, ~0 before you can change attributes, and
  315.         then re-attach the list.
  316.  
  317.     TAGS
  318.         SBNA_Left (WORD)
  319.         Left spacing offset of button from left of bar, set automatically.
  320.  
  321.         SBNA_Top (WORD)
  322.         Top spacing offset of button from top of bar, set automatically.
  323.  
  324.         SBNA_Width (WORD)
  325.         Width Of Button - these are set automatically.
  326.  
  327.         SBNA_Height (WORD)
  328.         Height Of Button - these are set automatically.
  329.  
  330.         SBNA_Image (struct Image *)
  331.         Standard Image or BOOPSI Image to be displayed in this button.
  332.  
  333.         SBNA_SelImage (struct Image *)
  334.         Standard Image or BOOPSI Image to be displayed in this button
  335.         when selected.
  336.  
  337.         SBNA_Spacing (WORD)
  338.         Spacing between this button and the last button.
  339.  
  340.         SBNA_Highlight (WORD)
  341.         Button selecting highlight mode, ant one of the following
  342.         is supported:
  343.  
  344.                 SBH_NONE        - Do not highlight.
  345.                 SBH_BACKFILL    - BackFill will FILLPEN
  346.                 SBH_RECESS      - Shift image right and down when selected.
  347.                 SBH_IMAGE       - Display alternate image (SBNA_SelImage)
  348.  
  349.         SBNA_Enabled (BOOL)
  350.         Enabled (hidden/shown) state of a speed button.
  351.  
  352.         SBNA_Help (STRPTR)
  353.         String Pointer to optional help text place in window titlebar
  354.         when this speed button is active/selected.
  355.  
  356.         SBNA_UserData (APTR)
  357.         User Data, use as desired.
  358.  
  359.         SBNA_Disabled (BOOL) (V41)
  360.         Marks this button as disabled, it will render with a ghost pattern
  361.         and will not allow it to be selected.
  362.  
  363.         SBNA_Toggle (BOOL) (V41)
  364.         Designates the button as a boolean toggle button. Defaults FALSE.
  365.  
  366.         SBNA_Selected (BOOL) (V41)
  367.         The current selection state of a Toggle/MX button. Defaults FALSE.
  368.  
  369.         SBNA_MXGroup (BOOL) (V41)
  370.         Set the MXGroup a button belongs in. This setting implies the
  371.         SBNA_Toggle setting as TRUE also. The default is ~0, or not
  372.         in any MXGroup. Note, a single speedbar can contain several
  373.         MX groupings and mixtures of toggles and normal selections!
  374.  
  375.     INPUTS
  376.         node - Node whose attributes you are changing.
  377.         taglist - Tag list of attributes to change.
  378.  
  379.     SEE ALSO
  380.         GetSpeedButtonNodeAttrsA()
  381.